fix(security): stop a project's CSRF policy blocking its own release asset build - #3641

The failure

A customer demo project set

security: { csrf: { excludePaths: ["/api/ag-ui"] } }

to keep CSRF enforced everywhere except the agent endpoint its chat client
posts to. Deploy then failed with

Release assets were not ready within 120s (last state: missing)

The developer compared manifests across releases — four consecutive releases
carrying a nested csrf object have no manifest, releases before and after
report state=ready — and shipped csrf: false on a sign-in-protected
customer demo because it was the only setting that deployed.

Mechanism

The manifest is built by the project runtime, not the CLI. The control plane
POSTs a signed operation envelope to
/api/control-plane/runs/{runId}/execute with
target: "task:release-asset-build"; that dispatch is the only caller of
beginReleaseAssetManifestBuild (src/release-assets/build-executor.ts:2297).
Until it lands, no manifest row exists and the state reads missing.

CsrfHandler (src/security/http/csrf/csrf-handler.ts:63) registers at
priority 5 with patterns: [], so it runs in front of
ProjectRunExecuteHandler for that POST
(src/server/runtime-handler/index.ts:138-159,
src/routing/registry/registry.ts:86-101). The control plane is not a browser:
it carries no __Host-vf_csrf cookie and authorizes from the JWS the handler
verifies. So the gate answered the project's own build dispatch with
403 Forbidden – invalid or missing CSRF token, the run failed before the
manifest existed, and the deploy surfaced 120 seconds later naming neither
CSRF nor config.

The boundary is not the nested object. csrf: true fails identically —
only an absent or false setting ever built a manifest. Absent is the common
case because the task rail dispatches to the main-branch runtime, which
resolves as preview, so the production csrf default never applies there
(src/security/http/config.ts:271). That is why manifests build for everyone
who never wrote the key.

Fix

isControlPlaneSurfaceRequest (src/channels/control-plane.ts) exempts the
signed control-plane prefix from the CSRF gate — the same shape as the existing
isCspReportRequest exemption, and for the same reason: the gate expects a
browser credential the caller cannot hold. Every handler behind that prefix
authenticates its envelope through verifyControlPlaneRequest before acting
(runs execute/resume/cancel/stream, agents list), so the exemption removes no
authorization. The prefix is matched against URL.pathname, which resolves dot
segments, and a path that merely starts alike
(/api/control-plane-mirror/...) stays gated.

Tests

src/release-assets/build-dispatch-security.test.ts drives the real chain —
CsrfHandler then ProjectRunExecuteHandler, with a real signed envelope —
across all four csrf shapes and asserts the release asset build executor is
reached.

Red, before the fix:

release assets: control-plane build dispatch ... builds a manifest when the project enables csrf with a boolean
error: AssertionError: Values are not equal: release asset build never started; runtime answered 403: Forbidden – invalid or missing CSRF token
-   false
+   true

release assets: control-plane build dispatch ... builds a manifest when the project excludes a path from csrf
error: AssertionError: Values are not equal: release asset build never started; runtime answered 403: Forbidden – invalid or missing CSRF token
-   false
+   true

FAILED | 0 passed (2 steps) | 1 failed (2 steps)

Green, after:

release assets: control-plane build dispatch ...
  builds a manifest when the project leaves csrf unset ... ok
  builds a manifest when the project disables csrf ... ok
  builds a manifest when the project enables csrf with a boolean ... ok
  builds a manifest when the project excludes a path from csrf ... ok
ok | 1 passed (4 steps) | 0 failed

Plus two cases in csrf-handler.test.ts: a run dispatch passes for every
enabled csrf shape, and a look-alike prefix is still rejected. No existing test
was changed or weakened.

Not fixed here, worth a follow-up

• AuthHandler has the same hole. It runs at priority 0, exempts only
  isCspReportRequest, and reads security.auth
  (src/security/http/auth.ts:156-183). A project that configures basic or
  bearer auth in veryfront.config.ts should be expected to 401 its own
  control-plane dispatches the same way. Not changed here because it needs its
  own reproduction rather than a symmetric guess.
• Legibility. This fix removes one instance; the shape stays. A config
  value can still stop a manifest with the failure surfacing 120 s later as a
  timeout that names no cause. What would close that: have deploy read the
  release-asset build run's terminal state and error alongside the manifest
  state, so last state: missing can say why the build never began.

Summary by CodeRabbit

• Bug Fixes

  • Improved reliability for signed control-plane operations by allowing valid requests to proceed without requiring a CSRF token.
  • Restricted this exception to recognized paths, supported methods, and valid signatures, preserving protection for look-alike or unrelated requests.
  • Ensured release-asset build dispatch works consistently across different CSRF configuration settings.

• Tests

  • Added coverage for successful dispatch, supported request variations, and rejection of invalid paths, methods, and signatures.